<html>
   <!-- $Id: quickStart.html,v 1.3 2006/07/17 10:26:18 grlea Exp $ -->
   <head>
      <title>Simple Log - Quick Start</title>
      <meta http-equiv="description" content="How to get up and running with Simple Log" />
      <link type="text/css" rel="stylesheet" href="style.css" />
      <link type="text/css" rel="stylesheet" href="code.css" />
   </head>

   <body>

      <div class="topMenu">
         <h1>Simple Log User Guide</h1>
         <ul>
            <li><a href="quickStart.html">Quick&nbsp;Start</a></li>
            <li><a href="philosophy.html">Philosophy</a></li>
            <li><a href="recommendedUse.html">Recommended&nbsp;Use</a></li>
            <li><a href="properties.html">Properties</a></li>
            <li><a href="rollover.html">Log&nbsp;Rolling</a></li>
            <li><a href="log4jComparison.html">Comparison&nbsp;with&nbsp;Log4J</a></li>
            <li><a href="faq.html">FAQ</a></li>
            <li><a href="donations.html">Donations</a></li>
            <li><a href="meaningOfLife.html">The Meaning of Life</a></li>
            <li><a href="api/index.html">API Documentation</a></li>
         </ul>
      </div>

      <h1>Simple Log - Quick Start</h1>

      <img src="images/paperPlane.png" alt="Paper Aeroplane" class="illustration"/>

      <p>
         Welcome to Simple Log.<br/>
         Seeing as this is a Quick Start, I'll try to keep the text to an absolute minumum.
         This document should describe enough about Simple Log for you to:
      </p>
      <ul>
         <li>Download Simple Log</li>
         <li>Get it in your classpath</li>
         <li>Use it in your code</li>
         <li>Deploy a configuration file</li>
         <li>See some output</li>
         <li>Change the debug and trace levels</li>
         <li>Output to a file</li>
         <li>Find other information</li>
      </ul>

      <p>
         If anything in this document is wrong, please <a href="mailto:owner@simple-log.dev.java.net">let me know</a>.
      </p>

      <h2>What to download</h2>

      <img src="images/download.png" alt="Download" class="illustration"/>

      <p>
         If you haven't already downloaded Simple Log, go to the
         <a href="https://simple-log.dev.java.net/downloads.html">Downloads page</a> and get the latest 'Full Release'.
      </p>

      <p>
         Unzip it into a place where you keep all your Java libraries.
         I put mine under <span class="filePath">C:\Java\lib\</span>.
         All files in the zip are under a subdirectory, so you don't need to create a directory to unzip into.
      </p>


      <h2>Which JARs to Use</h2>

      <p>
         You'll definitely want <span class="filePath">simple-log.jar</span> in your classpath.
         If you want <a href="rollover.html">log rolling</a>, you'll also need <span class="filePath">simple-log-rollover.jar</span>.
         You'll find both of these in the main directory of the release.
      </p>

      <p>
         If you are planning to use Simple Log as a provider for either Commons Logging or SLF4J, you will find additional JARs under the <span class="filePath">adapters/</span> directory that you'll need to use.
      </p>

      <h2>Which Files to Use</h2>

      <p>
         Simple Log also needs configuration files to make it do anything useful.
         All the configuration files you need are provided with Simple Log and you simply need to copy them and change them to suit your needs.
      </p>

      <p>
         You'll definitely want <span class="filePath">simplelog.properties</span> and <span class="filePath">simplelog-config.properties</span>.
         If you want <a href="rollover.html">log rolling</a>, you'll also need <span class="filePath">simplelog-rollover.properties</span>.
         All these files are in the <span class="filePath">properties/</span> directory of the release.
      </p>

      <h2>Where to put the JARs</h2>

      <img src="images/folders.png" alt="Folders" class="illustration"/>

      <p>
         I recommend putting the Simple Log JARs <b>in your application classpath</b>.
         If you are using a web or application user, I suggest putting the JARs in your <span class="filePath">WEB-INF/lib</span> or <span class="filePath">APP-INF/lib</span> directory.
      </p>

      <p>
         A guy once put the JARs in <span class="filePath">lib/ext</span> under his JRE and we spent a few hours and countless emails between us trying to figure out why it wouldn't load his configuration files. To summaries it real quick, Simple Log, by default, loads the configuration files from the classpath, and if you put the JARs in a ClassLoader that is higher in the hierarchy than the ClassLoader that the configuration files are in, you're going to have trouble. If that doesn't make sense to you, you probably need to do a bit more study on class loading.<br/>
         <a href="http://wiki.java.net/bin/view/Javapedia/Classloaders">Articles about Class Loading</a><br/>
         <a href="http://www.google.com.au/search?q=classloader+OR+%22class+Loading%22+introduction+OR+tutorial+OR+basics">Google for Class Loading tutorials</a>
      </p>


      <h2>Where to put the configuration</h2>

      <p>
         Put <span class="filePath">simplelog.properties</span> and <span class="filePath">simplelog-config.properties</span> in the root of your classpath.
         <span class="filePath">simplelog-rollover.properties</span> goes here too if you're using log rolling.
      </p>

      <p>
         By 'root of you classpath', I mean this:
         If you specify to your application:

            <pre class="commandLine">java -cp C:\myapplication\classes org.grlea.application.MyApplication</pre>

         and under that <span class="filePath">span class="filePath"</span> directory you have other subdirectories like this:

            <pre class="commandLine">C:\myapplication\classes\org\grlea\application</pre>

         then you want to put the configuration files in:

            <pre class="commandLine">C:\myapplication\classes\</pre>
      </p>

      <p>
         To word it another way, you need to put the configuration files in a directory that is <b><i>itself</i></b> on the classpath, not a directory this is <b><i>under</i></b> a directory that is on the classpath.
      </p>

      <p>
         If you're using an IDE, you'll probably want to put your configuration files at the root of your source tree and instruct the IDE to copy them over to the classes directory on compilation.
      </p>

      <p>
         If you're going to use Simple Log in a web application, it's best to place your configuration files in the <span class="filePath">WEB-INF/classes</span> directory, or in <span class="filePath">APP-INF/classes</span> for an application server.
         You'll probably also want to enable reloading, allowing you to change the configuration without restarting your server.
      </p>



      <h2>How to use Simple Log in Code</h2>

      <p>
         The normal way to use Simple Log from within your code is to create an instance of a SimpleLogger at the start of each class like this:

         <pre class="code">private static final SimpleLogger log = new SimpleLogger(HelloWorld.class);</pre>

         and then to use that logger throughout your class, like this:

         <pre class="code">
public class
SimpleLogTest
{
   private static final SimpleLogger log = new SimpleLogger(SimpleLogTest.class);

   public static void
   main(String[] argv)
   {
      log.entry("main");
      log.info("This is a test of Simple Log.");
      log.debugObject("argv", argv);
      log.exit("main");
   }
}
         </pre>
      </p>


      <h2>Try It Out!</h2>

      <p>
         If you copy the above code into your workspace, compile it, and run it with the Simple Log JARs and configuration files in the right place, you should see output very similar to the following:
      </p>

         <pre class="output">Mon 2006/05/01 20:34:01.243|   |main|SimpleLogTest|This is a test of Simple Log.</pre>

      <p>
         If you don't see anything, you've most likely put the configuration files in the wrong place. Either that, or you've already been playing with your configuration and you're outputting to a file and not to the console.
      </p>

      <h2>What to log at each level</h2>

      <p>
         Simple Log has seven levels at which information can be logged. The levels are:
      </p>
      <ol>
         <li>Fatal</li>
         <li>Error</li>
         <li>Warn</li>
         <li>Info</li>
         <li>Debug</li>
         <li>Verbose</li>
         <li>Ludicrous (the level you've always wanted but were always afraid to ask for)</li>
      </ol>

      <p>
         It's obviously best if everyone working on a project, if not everyone in the world, is using each level for similar types of information.
         To this end, each instance in the <a href="javadoc/org/grlea/log/DebugLevel.html">DebugLevel class</a> is documented so as to make it pretty clear what kind of information should be logged at that level.
      </p>

      <p>
         The tracing functionality, which is used to log entry to and exit from methods, is configured independently of the debug levels.
      </p>

      <h2>How to set debug levels</h2>

      <img src="images/controlKnob.png" alt="Controller" class="illustration"/>

      <p>
         Debug levels are set by creating a property in the simplelog.properties configuration file with the property name beng a class or package and the property value being either the name (e.g. Verbose) or number (e.g. 6) of the Debug Level to which that logger should be set.
      </p>

      <p>
         For example, if you executed the example SimpleLogTest class before and you got the output happening, you can now open up the <span class="filePath">simplelog.properties</span> file and enter this line at the end of it:

         <pre class="configuration">SimpleLogTest = verbose</pre>

         If you run the program again, you should see output like this:
      </p>

      <pre class="output">
Mon 2006/05/01 21:08:06.894|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:08:06.904|---|main|SimpleLogTest|argv|[]
</pre>

      <p>
         If you pass some arguments to the program, like this:

         <pre class="commandLine">java -cp .;C:\Java\lib\simple-log\2.0\simple-log.jar SimpleLogTest Testing debug of object array</pre>

         you'll see output like this:
      </p>

      <pre class="output">
Mon 2006/05/01 21:08:06.894|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:08:06.904|---|main|SimpleLogTest|argv|[Testing, debug, of, object, array]
</pre>

      <p>
         <b>Congratulations!</b><br/>
         You just logged an object!
         You should do more of that.
         It's one of the most useful things you can put in your log, and Simple Log makes it really easy to do.
      </p>

      <p>
         Note that we only didn't use the package name of this class because it doesn't have one. If it were in a package, we would need to use the fully-qualified name to configure it.
      </p>


      <h2>How to set trace flags</h2>

      <p>
         Tracing is configured using 'trace flags', and setting these is almost identical to setting debug levels. The main differences are that you need to put <span class="configuration">#trace</span> at the end of the class or package name, and the value is either <span class="configuration">true</span> or <span class="configuration">false</span>.
      </p>

      <p>
         So, if you now added this line to the end of your simplelog.properties:
      </p>

      <pre class="configuration">
SimpleLogTest#trace = true
</pre>

      <p>
         and re-run that program again, you should see this:
      </p>

<pre class="output">
Mon 2006/05/01 21:13:31.111|>>>|main|SimpleLogTest|main
Mon 2006/05/01 21:13:31.121|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:13:31.121|---|main|SimpleLogTest|argv|[Testing, debug, of, object, array]
Mon 2006/05/01 21:13:31.131|<<<|main|SimpleLogTest|main
</pre>

      <h2>Logging to a file</h2>

      <p>
         Up until now, the log output has always been coming out on the console (through System.err, no less). Most people, most of the time, prefer their logging to be written to a log file. With Simple Log, this is as easy as uncommenting a property and setting the value of it to be file name.
      </p>

      <p>
         So, open up <span class="filePath">simplelog-config.properties</span>, find the <span class="configuration">simplelog.logFile</span> property, uncomment it (by deleting the '#' at the start of the line) and write <span class="filePath">application.log</span> at the end of the line.
      </p>

      <p>
         Now, if you run the SimpleLogTest class again, you should see no output! However, you should find a file called <span class="filePath">application.log</span> in the application's working directory that contains the exact same output as it did before. (If you are running from the command line, the working directory should be whichever directory you were in when you ran the Java command. If you are using an IDE, the working directory is usually specified in the runtime configuration for the application.)
      </p>

      <p>
         If you want your logging to be written to a file as well as to the console, simply uncomment the <span class="configuration">simplelog.logFile.andConsole</span> property and change its value to <span class="configuration">true</span>.
      </p>


      <h2>That's It</h2>

      <p>
         So, you've now started with Simple Log, and I hope it was pretty quick.<br/>
         There are obviously many more things it can do that aren't covered here, and most of them are adequately explained in the configuration files and the <a href="javadoc/index.html">API documentation</a>. There are a few things, though, that can't be adequately communicated in a configuration file or at the top of a class, so you'll probably benefit from reading the rest of the documentation.
      </p>

      <p>
         Lastly, if you find that you save time or money by using Simple Log, I'd really appreciate it if you would consider saying thank you by GIVING ME MONEY. I've spent yonks on this thing, and I think my wife is starting to get really annoyed about it, but a little bit of money might make all the difference. See the <a href="donations.html">Donations page</a>. Thanks.
      </p>

      <p class="copyright">
         Copyright (c) 2006 Graham Lea. All rights reserved.
      </p>

      <div class="bottomMenu">
         <h1>Simple Log User Guide</h1>
         <ul>
            <li><a href="quickStart.html">Quick&nbsp;Start</a></li>
            <li><a href="philosophy.html">Philosophy</a></li>
            <li><a href="recommendedUse.html">Recommended&nbsp;Use</a></li>
            <li><a href="properties.html">Properties</a></li>
            <li><a href="rollover.html">Log&nbsp;Rolling</a></li>
            <li><a href="log4jComparison.html">Comparison&nbsp;with&nbsp;Log4J</a></li>
            <li><a href="faq.html">FAQ</a></li>
            <li><a href="donations.html">Donations</a></li>
            <li><a href="meaningOfLife.html">The Meaning of Life</a></li>
            <li><a href="api/index.html">API Documentation</a></li>
         </ul>
      </div>

   </body>

</html>
